<p></p>
<hr>
<h3>Example of File I/O</h3>
The sample program below will open a new file for writing, write text to it from a memory buffer, then close it.  The file will be created in the
directory in which RARS was run.
<p>
<pre>
# Sample program that writes to a new file.
#   by Kenneth Vollmar and Pete Sanderson

        .data
fout:   .asciz "testout.txt"      # filename for output
buffer: .asciz "The quick brown fox jumps over the lazy dog."
        .text
  ###############################################################
  # Open (for writing) a file that does not exist
  li   a7, 1024     # system call for open file
  la   a0, fout     # output file name
  li   a1, 1        # Open for writing (flags are 0: read, 1: write)
  ecall             # open a file (file descriptor returned in a0)
  mv   s6, a0       # save the file descriptor
  ###############################################################
  # Write to file just opened
  li   a7, 64       # system call for write to file
  mv   a0, s6       # file descriptor
  la   a1, buffer   # address of buffer from which to write
  li   a2, 44       # hardcoded buffer length
  ecall             # write to file
  ###############################################################
  # Close the file
  li   a7, 57       # system call for close file
  mv   a0, s6       # file descriptor to close
  ecall             # close file
  ###############################################################
</pre>
<p></p>
<hr>

<h3>Using MIDI output</h3>
These system services are unique to RARS, and provide a means of producing sound.  MIDI output is
simulated by your system sound card, and the simulation is provided by the <tt>javax.sound.midi</tt>
package.

<p>This service requires four parameters as follows:</p>
<table width="600" border="0" align="center" cellpadding="2">
    <tr>
        <td><h3>pitch (a0)</h3>

            <li>Accepts a positive byte value (0-127) that denotes a pitch as it would
                be represented in MIDI </li>

            <li>Each number is one semitone / half-step in the chromatic scale.</li>

            <li>0 represents a very low C and 127 represents a very high G (a standard
                88 key piano begins at 9-A and ends at 108-C).</li>
            <li>If the parameter value is outside this range, it applies a default value 60 which is the same as middle C on a piano.</li>

            <li>From middle C, all other pitches in the octave are as follows:</li>


            <table width="450" border="0" align="center" cellpadding="2">
                <tr>
                    <td>
                        <li>61 = C# or Db</li>
                        <li>62 = D</li>
                        <li>63 = D# or Eb</li>
                        <li>64 = E or Fb</li>
                    </td>
                    <td>
                        <li>65 = E# or F</li>
                        <li>66 = F# or Gb</li>
                        <li>67 = G</li>
                        <li>68 = G# or Ab</li>
                    </td>
                    <td>
                        <li>69 = A</li>
                        <li>70 = A# or Bb</li>
                        <li>71 = B or Cb</li>
                        <li>72 = B# or C</li>
                    </td>
                </tr>
            </table>


            <li>To produce these pitches in other octaves, add or subtract multiples
                of 12.</li>
            <br>
        </td>
    </tr>
    <tr>
        <td><h3>duration in milliseconds (a1)</h3>
            <li>Accepts a positive integer value that is the length of the tone in milliseconds.</li>
            <li>If the parameter value is negative, it applies a default value of one second (1000 milliseconds).</li>
            <br>
        </td>
    </tr>
    <tr>
        <td><h3>instrument (a2)</h3>
            <li>Accepts a positive byte value (0-127) that denotes the General MIDI
                &quot;patch&quot; used to play the tone.</li>
            <li>If the parameter is outside this range, it applies a default value 0 which is an <em>Acoustic Grand Piano</em>.</li>
            <li>General MIDI standardizes the number associated with each possible instrument
                (often referred to as <em>program change</em> numbers), however it does
                not determine how the tone will sound. This is determined by the synthesizer
                that is producing the sound. Thus a<em> Tuba</em> (patch 58) on one computer
                may sound different than that same patch on another computer.</li>
            <li>The 128 available patches are divided into instrument families of 8:</li>
            <table width="450" border="0" align="center" cellpadding="2">
                <tr>
                    <td width="60">0-7</td>
                    <td width="160">Piano</td>
                    <td width="60">64-71</td>
                    <td>Reed</td>
                </tr>
                <tr>
                    <td width="60">8-15</td>
                    <td width="160">Chromatic Percussion</td>
                    <td width="60">72-79</td>
                    <td>Pipe</td>
                </tr>
                <tr>
                    <td width="60">16-23</td>
                    <td width="160">Organ</td>
                    <td width="60">80-87</td>
                    <td>Synth Lead</td>
                </tr>
                <tr>
                    <td width="60">24-31</td>
                    <td width="160">Guitar</td>
                    <td width="60">88-95</td>
                    <td>Synth Pad</td>
                </tr>
                <tr>
                    <td width="60">32-39</td>
                    <td width="160">Bass</td>
                    <td width="60">96-103</td>
                    <td>Synth Effects</td>
                </tr>
                <tr>
                    <td width="60">40-47</td>
                    <td width="160">Strings</td>
                    <td width="60">104-111</td>
                    <td>Ethnic</td>
                </tr>
                <tr>
                    <td width="60">48-55</td>
                    <td width="160">Ensemble</td>
                    <td width="60">112-119</td>
                    <td>Percussion</td>
                </tr>
                <tr>
                    <td width="60">56-63</td>
                    <td width="160">Brass</td>
                    <td width="60">120-127</td>
                    <td>Sound Effects</td>
                </tr>
            </table>
            <li>Note that outside of Java, General MIDI usually refers to patches 1-128.
                When referring to a list of General MIDI patches, 1 must be subtracted
                to play the correct patch. For a full list of General MIDI instruments,
                see <a href="http://www.midi.org/">
                    www.midi.org/about-midi/gm/gm1sound.shtml</a>.
                The General MIDI channel 10 percussion key map is not relevant to the
                toneGenerator method because it always defaults to MIDI channel 1.</li>
            <br>
        </td>
    </tr>
    <tr>
        <td><h3>volume (a3)</h3>
            <li>Accepts a positive byte value (0-127) where 127 is the loudest and 0
                is silent. This value denotes MIDI velocity which refers to the initial
                attack of the tone.</li>
            <li>If the parameter value is outside this range, it applies a default value 100.</li>
            <li>MIDI velocity measures how hard a <em>note on</em> (or <em>note off</em>)
                message is played, perhaps on a MIDI controller like a keyboard. Most
                MIDI synthesizers will translate this into volume on a logarithmic scale
                in which the difference in amplitude decreases as the velocity value increases.</li>
            <li>Note that velocity value on more sophisticated synthesizers can also
                affect the timbre of the tone (as most instruments sound different when
                they are played louder or softer).</li>
        </td>
    </tr>
</table>
MIDI Output was developed and documented by Otterbein student Tony Brock in July 2007.
</body>
</html>